home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / cat3 / Preserve.3 < prev    next >
Text File  |  1994-09-20  |  5KB  |  133 lines
  1.  
  2.  
  3.  
  4. Tk_Preserve(3)        Tk Library Procedures
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      Tk_Preserve, Tk_Release, Tk_EventuallyFree -  avoid  freeing
  12.      storage while it's being used
  13.  
  14. SYNOPSIS
  15.      #include <tk.h>
  16.  
  17.      Tk_Preserve(_c_l_i_e_n_t_D_a_t_a)
  18.  
  19.      Tk_Release(_c_l_i_e_n_t_D_a_t_a)
  20.  
  21.      Tk_EventuallyFree(_c_l_i_e_n_t_D_a_t_a, _f_r_e_e_P_r_o_c)
  22.  
  23. ARGUMENTS
  24.      ClientData    _c_l_i_e_n_t_D_a_t_a   (in)      Token describing struc-
  25.                                           ture  to  be  freed  or
  26.                                           reallocated.  Usually a
  27.                                           pointer  to  memory for
  28.                                           structure.
  29.  
  30.      Tk_FreeProc   *_f_r_e_e_P_r_o_c    (in)      Procedure to invoke  to
  31.                                           free _c_l_i_e_n_t_D_a_t_a.
  32. _________________________________________________________________
  33.  
  34.  
  35. DESCRIPTION
  36.      These three procedures help  implement  a  simple  reference
  37.      count  mechanism for managing storage.  They are designed to
  38.      solve a problem having to do with widget deletion.   When  a
  39.      widget  is deleted, its widget record (the structure holding
  40.      information specific to the widget) must be returned to  the
  41.      storage  allocator.   However, it's possible that the widget
  42.      record is in active use by one  of  the  procedures  on  the
  43.      stack  at  the  time  of the deletion.  This can happen, for
  44.      example, if the command  associated  with  a  button  widget
  45.      causes  the  button  to  be destroyed:  an X event causes an
  46.      event-handling C procedure in  the  button  to  be  invoked,
  47.      which  in turn causes the button's associated Tcl command to
  48.      be executed, which in turn causes the button to be  deleted,
  49.      which  in  turn  causes the button's widget record to be de-
  50.      allocated.  Unfortunately, when the Tcl command returns, the
  51.      button's event-handling procedure will need to reference the
  52.      button's widget record.  Because of this, the widget  record
  53.      must  not  be  freed  as  part  of the deletion, but must be
  54.      retained until the  event-handling  procedure  has  finished
  55.      with  it.   In other situations where the widget is deleted,
  56.      it may be possible to free the widget record immediately.
  57.  
  58.      Tk_Preserve and Tk_Release  implement  short-term  reference
  59.      counts   for  their  _c_l_i_e_n_t_D_a_t_a  argument.   The  _c_l_i_e_n_t_D_a_t_a
  60.  
  61.  
  62.  
  63. Tk                                                              1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tk_Preserve(3)        Tk Library Procedures
  71.  
  72.  
  73.  
  74.      argument identifies an object and usually  consists  of  the
  75.      address of a structure.  The reference counts guarantee that
  76.      an object will not be freed until each call  to  Tk_Preserve
  77.      for  the  object  has  been  matched by calls to Tk_Release.
  78.      There may be any number of unmatched  Tk_Preserve  calls  in
  79.      effect at once.
  80.  
  81.      Tk_EventuallyFree is invoked to free up its _c_l_i_e_n_t_D_a_t_a argu-
  82.      ment.   It  checks to see if there are unmatched Tk_Preserve
  83.      calls for the object.  If not, then Tk_EventuallyFree  calls
  84.      _f_r_e_e_P_r_o_c  immediately.   Otherwise Tk_EventuallyFree records
  85.      the fact that _c_l_i_e_n_t_D_a_t_a needs eventually to be freed.  When
  86.      all  calls  to  Tk_Preserve  have been matched with calls to
  87.      Tk_Release then _f_r_e_e_P_r_o_c will be called by Tk_Release to  do
  88.      the cleanup.
  89.  
  90.      All the work  of  freeing  the  object  is  carried  out  by
  91.      _f_r_e_e_P_r_o_c.   _F_r_e_e_P_r_o_c  must  have  arguments  and result that
  92.      match the type Tk_FreeProc:
  93.           typedef void Tk_FreeProc(ClientData _c_l_i_e_n_t_D_a_t_a);
  94.      The _c_l_i_e_n_t_D_a_t_a argument to _f_r_e_e_P_r_o_c will be the same as  the
  95.      _c_l_i_e_n_t_D_a_t_a argument to Tk_EventuallyFree.
  96.  
  97.      This mechanism can be used to solve  the  problem  described
  98.      above  by  placing  Tk_Preserve  and Tk_Release calls around
  99.      actions that may cause undesired storage re-allocation.  The
  100.      mechanism  is  intended  only for short-term use (i.e. while
  101.      procedures are pending on the  stack);   it  will  not  work
  102.      efficiently  as  a mechanism for long-term reference counts.
  103.      The implementation does not depend in any way on the  inter-
  104.      nal  structure  of  the  objects  being freed;  it keeps the
  105.      reference counts in a separate structure.
  106.  
  107.  
  108. KEYWORDS
  109.      free, reference count, storage
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129. Tk                                                              2
  130.  
  131.  
  132.  
  133.